<h1>First steps</h1>

<h2>Download and extraction</h2>

<p>
The most simple way to get 7-Zip-JBinding to work is to download a pre-compiled binary package
for your operating system <a href="http://sourceforge.net/projects/sevenzipjbind/files/">here</a>.
All provided packages are Zip-compressed and you will need an extraction utility to expand them. For windows users
securing a copy of <a href="http://sevenzip.sourceforge.net/">7-Zip</a> is highly recommended. Linux and Mac OS X
users may use the corresponding command line tool <a href="http://p7zip.sourceforge.net/">p7Zip</a> or build-in Zip extractors.
</p>

<h2 id="maven">Get from maven central</h2>

<p>
There are two dependencies need to be added to the pom.xml file. 7-Zip-JBinding library jar and the platform dependend (native) jar.
</p>
<p>
<i>Note:</i> 7-Zip-JBinding library doesn't declare maven depenency to any platform jars. So you always need two &lt;dependency&gt; tags.
</p>

<p>
The simplest way to use 7-Zip-JBinding is to use the platform autodetection with the "all-platform" native package.
(The down side is the relatively big size of the "all-platform" jar though):
</p>

<pre>
&lt;dependency&gt;
    &lt;groupId&gt;net.sf.sevenzipjbinding&lt;/groupId&gt;
    &lt;artifactId&gt;<b>sevenzipjbinding</b>&lt;/artifactId&gt;
    &lt;version&gt;##INCLUDE_VERSION&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;net.sf.sevenzipjbinding&lt;/groupId&gt;
    &lt;artifactId&gt;sevenzipjbinding<b>-all-platforms</b>&lt;/artifactId&gt;
    &lt;version&gt;##INCLUDE_VERSION&lt;/version&gt;
&lt;/dependency&gt;
</pre>

<p>
Alternatively the proper platform jar artifact can be manually selected or selected using platform dependend maven profiles.
Here is a list of all available platform artifactIds:
</p>
<ul>
	<li>sevenzipjbinding-all-linux</li>
	<li>sevenzipjbinding-all-mac</li>
	<li>sevenzipjbinding-all-platforms</li>
	<li>sevenzipjbinding-all-windows</li>
	<li>sevenzipjbinding-linux-amd64</li>
	<li>sevenzipjbinding-linux-arm</li>
	<li>sevenzipjbinding-linux-i386</li>
	<li>sevenzipjbinding-mac-i386</li>
	<li>sevenzipjbinding-mac-x86_64</li>
	<li>sevenzipjbinding-windows-amd64</li>
	<li>sevenzipjbinding-windows-x86</li>
</ul>

<h2>Run an example</h2>

<p>
To use the 7-Zip-JBinding library you will need two JAR-files from <span class="filename">lib</span> folder of the
distribution in your classpath:
</p>

<ul>
	<li> <span class="filename">sevenzipjbinding.jar</span> - java part of 7-Zip-JBinding. 
		 (<a href="javadoc/index.html">JavaDoc</a>)</li>
	<li> <span class="filename">sevenzip-jbinding-&lsaquo;OS&rsaquo;.jar</span> - native libraries for
	the target operating system &lsaquo;OS&rsaquo;</li>
</ul>  

Here is a simple test program that can be used for checking all 7-Zip-JBinding requirements:
##INCLUDE_SNIPPET(SevenZipJBindingInitCheck)

<p>
To run this program correctly you will need to add two 7-Zip-JBinding JAR-files to the classpath.
On Linux it could be done as following:
</p>

<div class="fragment"><pre class="fragment">
$ java -cp &lsaquo;path-to-lib&rsaquo;/sevenzipjbinding.jar:             \  
           &lsaquo;path-to-lib&rsaquo;/sevenzipjbinding-Linux-i686.jar:. \ 
       SevenZipJBindingInitCheck
</pre></div>
 
<p>
Windows users can do the same with (written in a single line)
</p>

<div class="fragment"><pre class="fragment">
C:\Test&gt; java -cp &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding.jar;           \  
                  &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding-Windows-x86.jar;. \ 
              SevenZipJBindingInitCheck
</pre></div>

<p>
If the message
</p>

##INCLUDE_OUTPUT(SevenZipJBindingInitCheck)

<p>
shows up than 7-Zip-JBinding is working properly and is ready to use.
</p>

<br/>
<h2>Working with existing archives</h2>

<p>
Before you can do anything with an archive, you have to open it. In order to do this
you will need to call one of the corresponding static methods
SevenZip.openInArchive(...). The single
mandatory parameter is "inStream" - an implementation of the
IInStream interface.
</p>

<p>
In case you want to open an archive file from the file system 7-Zip-JBinding provides a standard implementation
of the IInStream interface:
RandomAccessFileInStream.
As the name says, this takes an instance of RandomAccessFile and uses it to provide an implementation of the IInStream.
</p>

<p>
Here is a simple example of how to open an archive from the file system: 
</p>

##INCLUDE_SNIPPET(SimpleOpen)

<p>
The opened archive can now be used for browsing or extraction operations. The last method called on archive should always be  
IInArchive.close().
It will close the archive and free system resources. The last, but not least, step is to close the random access file 
'<span class="java-field">randomAccessFile</span>' using close() method.
</p> 

<p>
Here is a complete program to print count of items in an archive of any supported format:
##INCLUDE_SNIPPET(PrintCountOfItems)
</p>

<p>
If you run this program with
</p>

<div class="fragment"><pre class="fragment">
C:\Test&gt; java -cp &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding.jar;           \  
                  &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding-Windows-x86.jar;. \ 
              PrintCountOfItems my-test-archive.zip
</pre></div>

<p>
you should get something like this:
</p>

##INCLUDE_OUTPUT(PrintCountOfItems)

<p>
Continue with <a href="extraction_snippets.html">extraction code snippets</a> to get more examples.
</p>

<br/>
<h2>Creating new archives</h2>

<p>
In order to create a new archive you need to call the corresponding open method of the SevenZip class first. Here
you should choose one of the archive format specific methods (like SevenZip.openOutArchiveZip(...) for Zip)
or use the archive format independent method SevenZip.openOutArchive(...). Lets use Zip-specific method and
see how a very simple Zip archive with a single item (archived file) containing a text message can be created.
</p>

<p>
There are 4 following steps involved:
<ul>
<li>Implement IOutCreateCallback&lt;IOutItemCallbackZip&gt; interface describing the archive item
<li>Open new out-archive
<li>Optionally configure the new archive (e.g. setting compression level)
<li>Call createArchive(...) method to create the new archive
</ul>
</p>

(<i>Note:</i> the following example snippet lacks the proper error handling
and shouldn't be used as a template for production code. See <a href="compression_snippets.html">compression/update code snippets</a> for complete examples)
<br>
<br>
Here is the complete class:

##INCLUDE_SNIPPET(CompressMessage)

<p>
If you run this program with
</p>

<div class="fragment"><pre class="fragment">
C:\Test&gt; java -cp &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding.jar;           \ 
                  &lsaquo;path-to-lib&rsaquo;\sevenzipjbinding-Windows-x86.jar;. \ 
              CompressMessage compressed_message.zip HelloWorld
</pre></div>

<p>
you will get the output
</p>

##INCLUDE_OUTPUT(CompressMessage)

<p>
Also the archive compressed_message.zip should be created. It contains single compressed file "message.txt" with the message "HelloWorld".
</p>

<div class="fragment"><pre class="fragment">
C:\Test&gt; 7z l compressed_message.zip
Listing archive: compressed_message.zip

--
Path = compressed_message.zip
Type = zip
Physical Size = 135

   Date      Time    Attr         Size   Compressed  Name
------------------- ----- ------------ ------------  ------------------------
2015-09-09 08:56:42 .....           15           15  message.txt
------------------- ----- ------------ ------------  ------------------------
                                    15           15  1 files, 0 folders
</pre></div>
<div class="fragment"><pre class="fragment">
C:\Test&gt; 7z x compressed_message.zip
Processing archive: compressed_message.zip

Extracting  message.txt

Everything is Ok

Size:       15
Compressed: 135
</pre></div>
<div class="fragment"><pre class="fragment">
C:\Test&gt; type message.txt
HelloWorld
</pre></div>

<p>
Continue with <a href="compression_snippets.html">compression/update code snippets</a> to get more examples.
</p>
